Virtual Earth Class Library for Visual FoxPro
Virtual Earth
Billed as “…the integrated mapping, imaging, search, and data visualization platform”, Microsoft’s Virtual Earth (VE) is an awesome mapping service that can be consumed and manipulated using the VE Map contol and JavaScript. In order to get a feel for what VE is capabable of, head on over to the VE Interactive SDK and try some of the examples provided. There is plenty of documentation, blog entries and articles available online that provide general VE overviews and detail the specific features the service provides, so I won’t spend a lot of time explaining what VE is and what it does. I want to explain enough so that you can understand the goals of the VFP Virtual Earth wrapper class library that I’m presenting in this blog entry. I figure you can do a few online searches if you’re interested in a deeper or broader understanding of VE and its specific features.
Virtual Earth Map Control
In order to understand VE from a developer standpoint you’ll need to be familiar with the Virtual Earth Map Control. The VE Map Control and the JavaScript classes/enumerations that make it up are provided via a web handler (.ashx file). I find it is more understandable to think of it as a library rather than a control. The VEMap class (which is part of the VE Map Control) is what I would consider the actual control that is seen within a web page. Perhaps I’m splitting hairs here, but I found it to be a helpful distinction in my mind when first starting to work with VE.
Creating Your First VE Web Page
It’s pretty simple to add the VE Map Control to a web page and use it to instantiate an instance of the VEMap class. Here’s the basic HTML needed in order to create such a page…
<html xmlns=“http://www.w3.org/1999/xhtml”>
<head>
<title>Virtual Earth</title>
<meta http-equiv=“Content-Type” content=“text/html; charset=utf-8” />
<script type=“text/javascript” src=“http://dev.virtualearth.net/mapcontrol/mapcontrol.ashx?v=6.2”></script>
<script type=“text/javascript”>
var map = null;
function startVE()
{
map = new VEMap(‘myMap’);
map.LoadMap();
}
function cleanUp()
{
if (map != null) map.Dispose();
}
</script>
</head>
<body onload=“startVE();” onunload=“cleanUp();” style=“margin: 0px”>
<div style=“overflow: hidden; width: 100%; height: 100%;” id=“myMap” />
</body>
</html>
You should note that the first script tag specifies the web handler mapcontrol.ashx as the source. Also, note how an instance of VEMap is created using the body’s onload and is eventually disposed of in the cleanUp() function via the body’s onunload. In any event, it’s pretty easy stuff given the results (go ahead and cut and paste that bit of code into an HTML file and view it in Internet Explorer).
What About Desktop Applications?
Obviously, given the architecture and heavy reliance on JavaScript, this stuff was made for web applications. But what about desktop applications that require geocoding of addresses, distance measurements, scheduling based on zones, or routing with turn-by-turn directions? I mean, Virtual Earth would work great if there was just some way to run an HTML page on a VFP form… Oh wait, Microsoft has provided us the WebBrowser control! Just drop that ActiveX control on a form and make a quick call to something like, Thisform.Olecontrol1.Navigate(“file:///C:\VETest.html”). Looks like we’re in business.
The only thing that’s left to do after that is write all of the JavaScript code that interacts with the VE Map Control. Awesome! Except that… erm… you may not know very much JavaScript (even though you’re a kick-butt VFP developer), and you may need VFP code to freely interact with the JavaScript objects (or vice versa), and how the heck do you get JavaScript to read your database where all of your addresses are stored? And… And…
Virtual Earth Wrapper for VFP
OK, so the previous section outlines the thought process that eventually lead to the class library that I built to tackle these problems. While working on a VFP project for a customer that involved VE, I looked at that list of classes and enumerations for the Virtual Earth Map Control version 6.2 and basically thought, “Wouldn’t it be super cool if those were all VFP classes??!!”.
I needed a class library (.vcx) wrapper for VE. This would contain all of the same classes (VFP equivalents) and a few super slick ways to commuicate and convert between VFP and JavaScript. With those in hand it would simply be a matter of hammering out the 5-10 thousand lines of code and comments to make it happen. I won’t go into the particulars of everything I ended up doing in order to make this work (you can look in the class library’s code yourself if you’re interested), but I did end up using the JSON class I created to handle most of the conversions and transport (data interchange) between the two languages.
As you’ll see in the download, the class library wrapper (virtualearth.vcx) is pretty much a carbon copy of the VE classes. So, most of the documentation and code that’s online for VE is of benefit when using it. In addition to the virtualearth.vcx, I’ve also provided a sample project and form (see screenshot below), so you can try this stuff out right away. The sample project is also intended to provide a little more information regarding how to do some of the things that a developer might want to do with VE in a desktop application. I usually find that learning by example is one of the fastest ways to get up to speed on a technology I’m not very familiar with.
Special Thank You
Before I wrap this blog entry up, I want to express my appreciation for Marc Lyon‘s efforts. He provided me early feedback and testing for this class library. His enthusiasm for this project was also one of the driving forces behind my completing it as fast as I did.
I also want to thank my client (you know who you are) who has been kind enough to allow me to share this work with the VFP Community. You’re about as generous and kind as they come.
What’s Next
Just have fun with Virtual Earth in VFP and see if virtualearth.vcx is useful to you and your applications. In a perfect world, you’d report back to me with any bugs you find, create some examples of your own and blog about them, or seek to improve the library in some way. If you do improve virtualearth.vcx, I’d appreciate it if you would contact me and share the improvements you’ve implemented. Thank you in advanced to those of you that decide to follow any of the above suggestions.
Until next time… Visual FoxPro Rocks!